void OnInit()

Obowiązkowo udostępniana przez skrypt dla programu

Wywoływana jest jednokrotnie podczas uruchamiania programu, po wczytaniu pliku AK i zainicjowaniu wszelkich struktur danych. Może posłużyć do inicjalizacji skryptu - wstępnego wypełnienia tablicy i innych przygotowań.

Przykład:

void OnInit()
{
  int x, y, w = GetWidth(), h = GetHeight();
  for (y = 0; y < h; y++) {
    for (x = 0; x < w; x++) {
      SetBuffer_b1(x, y, false);
    }
  }
}

void OnFrame()

Obowiązkowo udostępniana przez skrypt dla programu

Wywoływana jest w każdej iteracji. Jej zadaniem jest przeprowadzanie właściwych obliczeń na tablicy komórek.

Przykład:

void OnFrame()
{
  int x, y, w = GetWidth(), h = GetHeight();
  uint count;
  for (y = 0; y < h; y++) {
    for (x = 0; x < w; x++) {
      count = 0;
      if (GetBuffer_b1(x-1, y-1)) count++;
      if (GetBuffer_b1(x  , y-1)) count++;
      if (GetBuffer_b1(x+1, y-1)) count++;
      if (GetBuffer_b1(x-1, y  )) count++;
      if (GetBuffer_b1(x+1, y  )) count++;
      if (GetBuffer_b1(x-1, y+1)) count++;
      if (GetBuffer_b1(x  , y+1)) count++;
      if (GetBuffer_b1(x+1, y+1)) count++;

      if (count > 4)
        SetBuffer_b1(x, y, true);
      else if (count < 4)
        SetBuffer_b1(x, y, false);
    }
  }
}

void Beep(uint, uint)

Wydobywa z systemowego głośniczka (PC Speakera) dźwięk o podanej częstotliwości (w Hz) i czasie trwania (w ms). Na czas odgrywania dźwięku cały program zawiesza działanie, dlatego czas ten nie może być długi, a tej funkcji należy używać wyłącznie do celów debugowania.

Przykład:

Beep(1000, 100);

void Debug(int, int)

Wyświetla na pasku podpowiedzi w oknie programu podane dwie liczby całkowite. Będą tam widoczne do czasu ich zastąpienia przez nowy napis w wyniku ponownego wywołania tej funkcji, wyświetlenia podpowiedzi do kontrolki pod kursorem myszy itp.

void error(int)

Wywołuje błąd. Kończy działanie programu pozwalając przekazać kod błędu jako liczbę całkowitą.

Przykład:

if (count <= 0)
  error(13);

void assert(bool)

Wywołuje błąd, jeśli podana w nawiasie wartość logiczna albo wyrażenie nie jest prawdziwe. Służy do sprawdzania asercji, czyli warunków, które bezwzględnie powinny być spełnione w danym miejscu.

Przykład:

assert(count > 0);

Width, Height

Obowiązkowe
Typ: liczba całkowita (większa od zera, rozsądnie mała)

Określają szerokość i wysokość tablicy komórek.

Przykład:

Width = 100
Height = 75

int GetWidth()
int GetHeight()

Zwracają odpowiednio szerokość i wysokość tablicy w komórkach.

Wrap

Obowiązkowa
Typ: logiczny

• true - podczas odczytywania komórek spoza zakresu zwracane są wartości z tablicy po zawinięciu (powtórzeniu)
• false - podczas odczytywania komórek spoza zakresu zwracana jest wartość domyślna

Przykład:

Wrap = true

Default

Opcjonalna
Musi wystąpić poniżej Wrap
Może wystąpić tylko, jeśli Wrap = false

Określa wartość domyślną komórek, używaną podczas odczytywania komórek spoza zakresu tablicy.

Struktura: sekcja [], a w niej dowolne spośród składowych komórki i ich wartości odpowiedniego typu, w dowolnej kolejności.

Domyślnie:

b1,b2,b3,b4 = false
u1,u2,u3,u4 = 0
f1,f2,f3,f4 = 0.0

Przykład:

Default = [
  b1 = false
  f1 = 0.02
  u3 = 0
  u4 = 10
]

Buffers

Obowiązkowa
Wartość: 1, 2, 3

Określa rodzaj buforowania - ilu buforów ma używać program.

Przykład:

Buffers = 2

void SetBuffer_b1(int, int, bool)
void SetBuffer_b2(int, int, bool)
void SetBuffer_b3(int, int, bool)
void SetBuffer_b4(int, int, bool)
void SetBuffer_u1(int, int, uint)
void SetBuffer_u2(int, int, uint)
void SetBuffer_u3(int, int, uint)
void SetBuffer_u4(int, int, uint)
void SetBuffer_f1(int, int, float)
void SetBuffer_f2(int, int, float)
void SetBuffer_f3(int, int, float)
void SetBuffer_f4(int, int, float)

bool GetBuffer_b1(int, int)
bool GetBuffer_b2(int, int)
bool GetBuffer_b3(int, int)
bool GetBuffer_b4(int, int)
uint GetBuffer_u1(int, int)
uint GetBuffer_u2(int, int)
uint GetBuffer_u3(int, int)
uint GetBuffer_u4(int, int)
float GetBuffer_f1(int, int)
float GetBuffer_f2(int, int)
float GetBuffer_f3(int, int)
float GetBuffer_f4(int, int)

Funkcje do zapisywania i odczytywania poszczególnych składowych komórek tablicy (bufora) o podanych współrzędnych.

View

Wymagana

Ta sekcja określa sposób wizualizacji danych. Nie ma chyba innego wyjścia, niż rozpisać jej składnię na poszczególne elementy:

Cała wartość tej sekcji

Zależnie od wybranego trybu wizualizacji jedna z możliwości:

texture <kolor>

Komórki będą wizualizowane jako pojedyncze piksele tekstury, których kolor będzie obliczany w podany sposób. Jeśli wybiera się ten sposób wizualizacji, nie należy używać innych szerokości i wysokości tablicy, niż kwadratowych o boku będącym potęgą dwójki (np. 64x64, 128x128, 256x256). Inaczej mogą być problemy z utworzeniem takiej tekstury, a co za tym idzie z uruchomieniem programu, wyświetlaniem, rozkładaniem sąsiadująco itd. - ogólnie zachowanie jest wtedy niezdefiniowane.

cells <kolor>

Komórki będą wizualizowane jako kwadraciki, których kolor będzie obliczany w podany sposób, przedzielone marginesem o szerokości jednego piksela i kolorze tła.

vectors <wektor>

Komórki będą wizualizowane jako strzałeczki. Można zmieniać ich kolor, wielkość oraz kierunek. Aby były dobrze widoczne, rozmiary tablicy nie powinny być w tym trybie wizualizacji zbyt duże (np. może to być 40x30).

complex <complex>

Komórki w tym trybie będą wizualizowane każda bądź jako kwadracik (jak w cells), bądź jako strzałeczka (jak w vectors), zależnie od wartości jednego z pól komórki typu bool.

complex

Dowolna kolejność cells i vectors, dowolna kolejność false i true, np.:

[
  <b>
  false = cells <kolor>
  true = vectors <wektor>
]

W ten sposób definiuje się pole typu bool, od którego będzie zależał rodzaj wizualizacji każdej komórki i jaka jego wartość logiczna odpowiada jakiemu rodzajowi wizualizacji wraz z jego parametrami.

wektor

Jedna z możliwości:

[ <kolor> x = <wielkość> y = <wielkość> ]

Określa sposób obliczania koloru oraz współrzędnych X i Y wektora (współrzędne kartezjańskie).

[ <kolor> r = <wielkość> alfa = <wielkość> ]

Określa sposób obliczania koloru oraz długości i kąta nachylenia wektora (współrzędne biegunowe).

wielkość

Jedna z możliwości:

default

Użyta zostanie stała wartość domyślna, zależna od kontekstu użycia tej wartości.

<b>

Użyte zostanie podane pole typu bool, którego wartości logiczne będą odpowiadały dwóm możliwym stanom, zależnie od kontekstu użycia tej wartości.

<u> [ <liczba1> .. <liczba2> ]

Użyte zostanie podane pole typu uint, którego wartości będą się mieściły w podanym przedziale liczbowym. Jeśli wartości tego pola będą wychodziły poza ten przedział, zachowanie jest niezdefiniowane (np. mogą zostać ograniczone do minimalnej/maksymalnej wartości albo strzałka może wychodzić poza swoje pole).

<f> [ <liczba1> .. <liczba2> ]

Użyte zostanie podane pole typu float, którego wartości będą się mieściły w podanym przedziale liczbowym. Jeśli wartości tego pola będą wychodziły poza ten przedział, zachowanie jest niezdefiniowane (np. mogą zostać ograniczone do minimalnej/maksymalnej wartości albo strzałka może wychodzić poza swoje pole).

kolor

Jedna z możliwości:

<k>

Użyta zostanie podana, stała wartość koloru.

<b> [ false = <k>, true = <k> ]

Użyty zostanie jeden z dwóch podanych kolorów, zależnie od wartości logicznej podanego pola typu bool.

<b> [ double <k> <k> <k> <k> ]

Użyty zostanie jeden z czterech podanych kolorów, zależnie od wartości podanego pola typu bool w tablicy poprzedniej i aktualnej. Tej opcji wolno używać tylko, kiedy zastosowane jest potrójne buforowanie. Kolejne wartości kolorów odpowiadają odpowiednio:

1. Wartość poprzednia false, wartość obecna false
2. Wartość poprzednia false, wartość obecna true
3. Wartość poprzednia true, wartość obecna false
4. Wartość poprzednia true, wartość obecna true

<u> [ RGB ]

Użyte zostanie podane pole typu uint interpretowane bezpośrednio jako wartość koloru XRGB. Najstarszy bajt jest ignorowany, pozostałe odpowiadają poszczególnym składowym koloru.

<u> [ list <liczba> <k> <liczba> <k> ... ]

Użyty zostanie jeden z kolorów odpowiadających podanym, dyskretnym wartościom podanego pola typu uint. Ta opcja przydatna jest podczas wykorzystywania takiego pola jako wartości wyliczeniowej - przyjmującej jedną z kilku wartości. Jeśli wartości nie ma na liście, zachowanie jest niezdefiniowane.

<u> [ gradient <liczba> = <k> .. <liczba> = <k> ]

<f> [ gradient <liczba> = <k> .. <liczba> = <k> ]

Użyty zostanie jeden z kolorów pośrednich pomiędzy pierwszym, a drugim z podanych, zależnie proporcjonalnie od wartości podanego pola spomiędzy pierwszej, a drugiej podanej wartości liczbowej.

<u> [ rainbow <liczba> .. <liczba> ]

<f> [ rainbow <liczba> .. <liczba> ]

Użyty zostanie jeden z kolorów tęczy, zależnie proporcjonalnie od wartości podanego pola spomiędzy pierwszej, a drugiej podanej wartości liczbowej.

b

Nazwa jednego ze składników komórki typu bool - b1, b2, b3, b4.

u

Nazwa jednego ze składników komórki typu uint - u1, u2, u3, u4.

f

Nazwa jednego ze składników komórki typu float - f1, f2, f3, f4.

k

Wartość koloru - jedna z 16 dozwolonych nazw lub liczba szesnastkowa, tak jak zostało to opisane wyżej.

liczba

Wartość liczbowa, zależnie od kontekstu całkowita lub rzeczywista.

Przykłady:

View = cells b1 [ false = 606060, true = white ]

Komórki wizualizowane będą jako kwadraciki o kolorze zależnym od pola b1. Jeśli w danej komórce to pole ma wartość false, do jej narysowania użyty zostanie kolor ciemny szary. Jeśli ma wartość true, użyty zostanie kolor biały.

View = texture u1 [ RGB ]

Tablica rysowana będzie w postaci tekstury, a kolory jej pikseli będą odpowiadały wartościom liczbowym pól u1 w poszczególnych komórkach interpretowanym bezpośrednio jako wartość liczbowa koloru.

View = complex [
  b1
  true = cells
    silver
  false = vectors [
    f1 [ rainbow 0.0 .. 1.0 ]
    x = f2 [ -1.0 .. +1.0 ]
    y = f3 [ -1.0 .. +1.0 ]
  ]
]

Jeśli dana komórka ma pole b1 równe true, przedstawiana będzie jako kwadracik w kolorze jasnym szarym. Jeśli ma to pole równe false, przedstawiana będzie jako strzałeczka, której kolor ma być kolorem tęczy zależnym od pola f1 (które przyjmuje wartości z zakresu od 0.0 - tej wartości będzie odpowiadał kolor czerwony, do 1.0 - tej wartości będzie odpowiadał kolor niebieski), a kierunek wektora opisują współrzędne: X podana w polu f2 i Y podana w polu f3.

uint InterpolateColor(uint, uint, float)

Zwraca kolor zinterpolowany pomiędzy dwoma podanymi, zależnie od wartości liczbowej trzeciego parametru z zakresu od 0.0 do 1.0.

Najstarszy bajt zwracanego koloru oficjalnie jest niezdefiniowany. Nieoficjalnie, w obecnej wersji jest zawsze równy 0xFF :)

Przykład:

InterpolateColor(0x000000, 0xFFFFFF, 0.5)

Zwraca kolor szary równo w połowie między czarnym, a białym.

uint RainbowColor(float)

Zwraca jeden z kolorów tęczy zależnie od podanej wartości liczbowej z zakresu od 0.0 do 1.0.

Najstarszy bajt zwracanego koloru oficjalnie jest niezdefiniowany. Nieoficjalnie, w obecnej wersji jest zawsze równy 0x00 :)

float Grayscale(uint)

Zwraca wartość z zakresu od 0.0 do 1.0 po przetworzeniu podanego koloru na odcień szarości.

Przykład:

SetBuffer_b1(x, y, Grayscale(GetBuffer_u1(x, y)) >= 0.5);

Buttons

Opcjonalna
Struktura: [ <numer> = <etykieta>, <numer> = <etykieta>, ... ]

Określa, które przyciski mają być widoczne i nadaje im etykiety tekstowe.

Przykład:

Buttons = [
  1 = "Wyczyść"
  2 = "Zmień 10%"
  3 = "Wypełnij 50%"

  4 = "Rysuj 0"
  5 = "Rysuj 1"

  7 = "Linia"
  8 = "Prostokąt"
]

void OnButton1()
void OnButton2()
void OnButton3()
void OnButton4()
void OnButton5()
void OnButton6()
void OnButton7()
void OnButton8()
void OnButton9()
void OnButton0()

Opcjonalnie udostępniane przez skrypt dla programu

Wywoływane są po naciśnięciu odpowiedniego przycisku za pomocą myszki lub skrótu klawiszowego.

bool GetButtonDown(int)
void SetButtonDown(int, bool)

Zwraca lub ustawia stan wciśnięcia przycisku o podanym numerze.

Przykład:

bool CzymRysowac;

void OnButton4()
{  
  CzymRysowac = false;
  SetButtonDown(4, true);
  SetButtonDown(5, false);
}

void OnButton5()
{
  CzymRysowac = true;
  SetButtonDown(4, false);
  SetButtonDown(5, true);
}

void OnMouseDown(const int, const int)

Opcjonalnie udostępniana przez skrypt dla programu

Wywoływana jest po wciśnięciu przez użytkownika lewego przycisku myszki nad obszarem tablicy. Przekazane zostają współrzędne wskazanej komórki tablicy.

void OnMouseUp(const int, const int)

Opcjonalnie udostępniana przez skrypt dla programu

Wywoływana jest po zwolnieniu przez użytkownika lewego przycisku myszki nad obszarem tablicy. Przekazane zostają współrzędne wskazanej komórki tablicy.

void OnMouseMove(const int, const int)

Opcjonalnie udostępniana przez skrypt dla programu

Wywoływana jest po przesunięciu kursora myszy nad obszarem tablicy, ale tylko, jeśli lewy przycisk myszy jest wciśnięty. Przekazane zostają współrzędne wskazywanej komórki tablicy.

Przykład:

int LastX, LastY;

void OnMouseDown(const int x, const int y)
{
  // Zapamiętaj pozycję początkową
  LastX = x; LastY = y;
}

void OnMouseUp(const int x, const int y)
{
  // Narysuj prostokąt
  int ix, iy;
  int x1 = min_i(x, LastX), x2 = max_i(x, LastX);
  int y1 = min_i(y, LastY), y2 = max_i(y, LastY);
  for (iy = y1; iy <= y2; iy++) {
    for (ix = x1; ix <= x2; ix++) {
      SetBuffer_b1(ix, iy, true);
    }
  }
}